Release 10.1A: OpenEdge Application Server:
Developing AppServer Applications

Understanding procedure handles in distributed Progress 4GL sessions

Every active Progress 4GL procedure, whether running on a Progress 4GL client or in an AppServer agent, has a procedure handle associated with it. Among the various attributes of the procedure handle, the PROXY, REMOTE, and PERSISTENT attributes combine to provide important information about the procedure and its handle in a distributed application environment.

REMOTE attribute

The THIS-PROCEDURE system handle returns the current procedure handle value from within any executing block of an external procedure. A current procedure handle created within an AppServer session for a remote procedure request is a remote procedure handle. Its REMOTE attribute is, therefore, set to TRUE. If the REMOTE attribute is FALSE, then the current procedure was created as the result of a local procedure call (that is, a procedure call initiated and executed within the current Progress 4GL session context).

PERSISTENT attribute

When you execute a persistent procedure from a local procedure call, as with any procedure, the persistent procedure can reference its own context using the THIS-PROCEDURE system handle. This system handle returns a procedure handle to the persistent procedure’s own context.

Also, the procedure that executes the RUN statement that creates the persistent procedure can obtain a reference to the same persistent procedure context using the SET option of the RUN statement. This option returns the same procedure handle as the THIS-PROCEDURE system handle accessed from within the persistent procedure.

Thus, for a local persistent procedure, there is only one handle for a specific persistent procedure context, but there might be many references to it. For any such reference to a persistent procedure handle, the PERSISTENT attribute returns the value TRUE.

PROXY attribute

When a Progress 4GL client application executes a remote persistent procedure, two persistent procedure handles are created: one within the client application session and another separate handle within the AppServer session where the persistent procedure is created. OpenEdge internally maintains a mapping between the two handles. The handle within the client application is a proxy persistent procedure handle, and its PROXY attribute and its PERSISTENT attributes are set to TRUE, but its REMOTE attribute is FALSE. The handle within the AppServer agent is a remote persistent procedure handle, and its REMOTE attribute and the PERSISTENT attribute are set to TRUE, but its PROXY attribute is FALSE.

Unlike persistent procedure handles used for local procedures, the proxy persistent procedure handle and the remote persistent procedure handle are truly separate handles. For example, setting the PRIVATE-DATA attribute on a remote persistent procedure handle has no effect on the PRIVATE-DATA attribute of the corresponding proxy persistent procedure handle.

How the attributes work together

Table 4–8 summarizes the settings of the PROXY, REMOTE, and PERSISTENT procedure handle attributes for various types of procedure call scenarios.

Table 4–8: PROXY, REMOTE, and PERSISTENT procedure handle attribute settings 

Procedure call type	Caller handle	Callee handle (THIS-PROCEDURE)
Local Procedure	Not applicable	PROXY      = FALSE REMOTE     = FALSE PERSISTENT = FALSE
Local Persistent Procedure	PROXY      = FALSE REMOTE     = FALSE PERSISTENT = TRUE	PROXY      = FALSE REMOTE     = FALSE PERSISTENT = TRUE
Remote Procedure	Not applicable	PROXY      = FALSE REMOTE     = TRUE PERSISTENT = FALSE
Remote Persistent Procedure	PROXY      = TRUE REMOTE     = FALSE PERSISTENT = TRUE	PROXY      = FALSE REMOTE     = TRUE PERSISTENT = TRUE

In Table 4–8, Caller Handle refers to the handle returned by the RUN statement. This column is relevant only for persistent procedures because you can only reference the procedure handle of a procedure that you call persistently using the SET option of the RUN statement. Callee Handle refers to the procedure handle within the procedure that is being executed. You can reference this handle using the THIS-PROCEDURE system handle, whether or not the current procedure was called persistently.